<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /fasttmp/mkdist-qt-4.3.5-1211793125/qtopia-core-opensource-src-4.3.5/doc/src/qtnetwork.qdoc -->
<head>
  <title>Qt 4.3: QtNetwork Module</title>
  <link rel="prev" href="qtgui.html" />
  <link rel="contents" href="modules.html" />
  <link rel="next" href="qtopengl.html" />
  <link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
<td width="1">&nbsp;&nbsp;</td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a>&nbsp;&middot; <a href="classes.html"><font color="#004faf">All&nbsp;Classes</font></a>&nbsp;&middot; <a href="mainclasses.html"><font color="#004faf">Main&nbsp;Classes</font></a>&nbsp;&middot; <a href="groups.html"><font color="#004faf">Grouped&nbsp;Classes</font></a>&nbsp;&middot; <a href="modules.html"><font color="#004faf">Modules</font></a>&nbsp;&middot; <a href="functions.html"><font color="#004faf">Functions</font></a></td>
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><p>
[Previous: <a href="qtgui.html">QtGui Module</a>]
[<a href="modules.html">Qt's Modules</a>]
[Next: <a href="qtopengl.html">QtOpenGL Module</a>]
</p>
<h1 align="center">QtNetwork Module<br /><small></small></h1>
<p>The QtNetwork module offers classes that allow you to write TCP/IP clients and servers. <a href="#details">More...</a></p>
<h2>Namespaces</h2>
<p><table width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0">
<tr valign="top" class="odd"><th><a href="qssl.html">QSsl</a></th><td>Declares enums common to all SSL classes in QtNetwork</td></tr>
</table></p>
<h2>Classes</h2>
<p><table width="100%" class="annotated" cellpadding="2" cellspacing="1" border="0">
<tr valign="top" class="odd"><th><a href="qabstractsocket.html">QAbstractSocket</a></th><td>The base functionality common to all socket types</td></tr>
<tr valign="top" class="even"><th><a href="qauthenticator.html">QAuthenticator</a></th><td>Authentication object</td></tr>
<tr valign="top" class="odd"><th><a href="qftp.html">QFtp</a></th><td>Implementation of the client side of FTP protocol</td></tr>
<tr valign="top" class="even"><th><a href="qhostaddress.html">QHostAddress</a></th><td>IP address</td></tr>
<tr valign="top" class="odd"><th><a href="qhostinfo.html">QHostInfo</a></th><td>Static functions for host name lookups</td></tr>
<tr valign="top" class="even"><th><a href="qhttp.html">QHttp</a></th><td>Implementation of the HTTP protocol</td></tr>
<tr valign="top" class="odd"><th><a href="qhttpheader.html">QHttpHeader</a></th><td>Header information for HTTP</td></tr>
<tr valign="top" class="even"><th><a href="qhttprequestheader.html">QHttpRequestHeader</a></th><td>Request header information for HTTP</td></tr>
<tr valign="top" class="odd"><th><a href="qhttpresponseheader.html">QHttpResponseHeader</a></th><td>Response header information for HTTP</td></tr>
<tr valign="top" class="even"><th><a href="qnetworkaddressentry.html">QNetworkAddressEntry</a></th><td>Stores one IP address supported by a network interface, along with its associated netmask and broadcast address</td></tr>
<tr valign="top" class="odd"><th><a href="qnetworkinterface.html">QNetworkInterface</a></th><td>Listing of the host's IP addresses and network interfaces</td></tr>
<tr valign="top" class="even"><th><a href="qnetworkproxy.html">QNetworkProxy</a></th><td>Network layer proxy</td></tr>
<tr valign="top" class="odd"><th><a href="qsslcertificate.html">QSslCertificate</a></th><td>Convenient API for an X509 certificate</td></tr>
<tr valign="top" class="even"><th><a href="qsslcipher.html">QSslCipher</a></th><td>Represents an SSL cryptographic cipher</td></tr>
<tr valign="top" class="odd"><th><a href="qsslerror.html">QSslError</a></th><td>SSL error</td></tr>
<tr valign="top" class="even"><th><a href="qsslkey.html">QSslKey</a></th><td>Interface for private and public keys</td></tr>
<tr valign="top" class="odd"><th><a href="qsslsocket.html">QSslSocket</a></th><td>SSL encrypted socket for both clients and servers</td></tr>
<tr valign="top" class="even"><th><a href="qtcpserver.html">QTcpServer</a></th><td>TCP-based server</td></tr>
<tr valign="top" class="odd"><th><a href="qtcpsocket.html">QTcpSocket</a></th><td>TCP socket</td></tr>
<tr valign="top" class="even"><th><a href="qudpsocket.html">QUdpSocket</a></th><td>UDP socket</td></tr>
<tr valign="top" class="odd"><th><a href="qurlinfo.html">QUrlInfo</a></th><td>Stores information about URLs</td></tr>
</table></p>
<a name="details"></a>
<h2>Detailed Description</h2>
<p>The network module provides classes to make network programming easier and portable. It offers both high-level classes such as <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a> that implement specific application-level protocols, and lower-level classes such as <a href="qtcpsocket.html">QTcpSocket</a>, <a href="qtcpserver.html">QTcpServer</a>, and <a href="qudpsocket.html">QUdpSocket</a>.</p>
<p>The QtNetwork module is part of the <a href="commercialeditions.html#qt-console-edition">Qt Console Edition</a>, the <a href="commercialeditions.html#qt-desktop-edition">Qt Desktop Edition</a>, and the <a href="opensourceedition.html">Qt Open Source Edition</a>.</p>
<p>Topics:</p>
<ul><li><a href="#configuring-the-build-process">Configuring the Build Process</a></li>
<li><a href="#writing-http-and-ftp-clients-with-qhttp-and-qftp">Writing HTTP and FTP Clients with QHttp and QFtp</a></li>
<li><a href="#using-tcp-with-qtcpsocket-and-qtcpserver">Using TCP with QTcpSocket and QTcpServer</a></li>
<li><a href="#using-udp-with-qudpsocket">Using UDP with QUdpSocket</a></li>
<li><a href="#resolving-host-names-using-qhostinfo">Resolving Host Names using QHostInfo</a></li>
</ul>
<a name="configuring-the-build-process"></a>
<h3>Configuring the Build Process</h3>
<p>Applications that use Qt's networking classes need to be configured to be built against the QtNetwork module. The following declaration in a <tt>qmake</tt> project file ensures that an application is compiled and linked appropriately:</p>
<pre> QT += network</pre>
<p>This line is necessary because only the <a href="qtcore.html">QtCore</a> and <a href="qtgui.html">QtGui</a> modules are used in the default build process.</p>
<p>To include the definitions of the module's classes, use the following directive:</p>
<pre> #include &lt;QtNetwork&gt;</pre>
<a name="writing-http-and-ftp-clients-with-qhttp-and-qftp"></a>
<h3>Writing HTTP and FTP Clients with QHttp and QFtp</h3>
<p>HTTP (Hypertext Transfer Protocol) is an application-level network protocol used mainly for downloading HTML and XML files, but it is also used as a high-level transport protocol for many other types of data, from images and movies to purchase orders and banking transactions. In contrast, FTP (File Transfer Protocol) is a protocol used almost exclusively for browsing remote directories and for transferring files.</p>
<p align="center"><img src="images/httpstack.png" alt="HTTP Client and Server" /></p><p>HTTP is a simpler protocol than FTP in many ways. It uses only one network connection, while FTP uses two (one for sending commands, and one for transferring data). HTTP is a stateless protocol; requests and responses are always self-contained. The FTP protocol has a state and requires the client to send several commands before a file transfer takes place.</p>
<p>In practice, HTTP clients often use separate connections for separate requests, whereas FTP clients establish one connection and keep it open throughout the session.</p>
<p>The <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a> classes provide client-side support for HTTP and FTP. Since the two protocols are used to solve the same problems, the <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a> classes have many features in common:</p>
<ul>
<li><i>Non-blocking behavior.</i> <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a> are asynchronous. You can schedule a series of commands (also called &quot;requests&quot; for HTTP). The commands are executed later, when control returns to Qt's event loop.</li>
<li><i>Command IDs.</i> Each command has a unique ID number that you can use to follow the execution of the command. For example, <a href="qftp.html">QFtp</a> emits the <a href="qftp.html#commandStarted">commandStarted()</a> and <a href="qftp.html#commandFinished">commandFinished()</a> signal with the command ID for each command that is executed. <a href="qhttp.html">QHttp</a> has a <a href="qhttp.html#requestStarted">requestStarted()</a> and a <a href="qhttp.html#requestFinished">requestFinished()</a> signal that work the same way.</li>
<li><i>Data transfer progress indicators.</i> <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a> emit signals whenever data is transferred (<a href="qftp.html#dataTransferProgress">QFtp::dataTransferProgress</a>(), <a href="qhttp.html#dataReadProgress">QHttp::dataReadProgress</a>(), and <a href="qhttp.html#dataSendProgress">QHttp::dataSendProgress</a>()). You could connect these signals to QProgressBar::setProgress() or QProgressDialog::setProgress(), for example.</li>
<li><i><a href="qiodevice.html">QIODevice</a> support.</i> Both classes support convenient uploading from and downloading to <a href="qiodevice.html">QIODevice</a>s, in addition to a <a href="qbytearray.html">QByteArray</a>-based API.</li>
</ul>
<p>There are two main ways of using <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a>. The most common approach is to keep track of the command IDs and follow the execution of every command by connecting to the appropriate signals. The other approach is to schedule all commands at once and only connect to the done() signal, which is emitted when all scheduled commands have been executed. The first approach requires more work, but it gives you more control over the execution of individual commands and allows you to initiate new commands based on the result of a previous command. It also enables you to provide detailed feedback to the user.</p>
<p>The <a href="network-http.html">HTTP</a> and <a href="network-ftp.html">FTP</a> examples illustrate how to write an HTTP and an FTP client.</p>
<p>Writing your own HTTP or FTP server is possible using the lower-level classes <a href="qtcpsocket.html">QTcpSocket</a> and <a href="qtcpserver.html">QTcpServer</a>.</p>
<a name="using-tcp-with-qtcpsocket-and-qtcpserver"></a>
<h3>Using TCP with QTcpSocket and QTcpServer</h3>
<p>TCP (Transmission Control Protocol) is a low-level network protocol used by most Internet protocols, including HTTP and FTP, for data transfer. It is a reliable, stream-oriented, connection-oriented transport protocol. It is particularly well suited to the continuous transmission of data.</p>
<p align="center"><img src="images/tcpstream.png" alt="A TCP Stream" /></p><p>The <a href="qtcpsocket.html">QTcpSocket</a> class provides an interface for TCP. You can use <a href="qtcpsocket.html">QTcpSocket</a> to implement standard network protocols such as POP3, SMTP, and NNTP, as well as custom protocols.</p>
<p>A TCP connection must be established to a remote host and port before any data transfer can begin. Once the connection has been established, the IP address and port of the peer are available through <a href="qabstractsocket.html#peerAddress">QTcpSocket::peerAddress</a>() and <a href="qabstractsocket.html#peerPort">QTcpSocket::peerPort</a>(). At any time, the peer can close the connection, and data transfer will then stop immediately.</p>
<p><a href="qtcpsocket.html">QTcpSocket</a> works asynchronously and emits signals to report status changes and errors, just like <a href="qhttp.html">QHttp</a> and <a href="qftp.html">QFtp</a>. It relies on the event loop to detect incoming data and to automatically flush outgoing data. You can write data to the socket using <a href="qiodevice.html#write">QTcpSocket::write</a>(), and read data using <a href="qiodevice.html#read">QTcpSocket::read</a>(). <a href="qtcpsocket.html">QTcpSocket</a> represents two independent streams of data: one for reading and one for writing.</p>
<p>Since <a href="qtcpsocket.html">QTcpSocket</a> inherits <a href="qiodevice.html">QIODevice</a>, you can use it with <a href="qtextstream.html">QTextStream</a> and <a href="qdatastream.html">QDataStream</a>. When reading from a <a href="qtcpsocket.html">QTcpSocket</a>, you must make sure that enough data is available by calling <a href="qabstractsocket.html#bytesAvailable">QTcpSocket::bytesAvailable</a>() beforehand.</p>
<p>If you need to handle incoming TCP connections (e.g&#x2e;, in a server application), use the <a href="qtcpserver.html">QTcpServer</a> class. Call <a href="qtcpserver.html#listen">QTcpServer::listen</a>() to set up the server, and connect to the <a href="qtcpserver.html#newConnection">QTcpServer::newConnection</a>() signal, which is emitted once for every client that connects. In your slot, call <a href="qtcpserver.html#nextPendingConnection">QTcpServer::nextPendingConnection</a>() to accept the connection and use the returned <a href="qtcpsocket.html">QTcpSocket</a> to communicate with the client.</p>
<p>Although most of its functions work asynchronously, it's possible to use <a href="qtcpsocket.html">QTcpSocket</a> synchronously (i.e&#x2e;, blocking). To get blocking behavior, call <a href="qtcpsocket.html">QTcpSocket</a>'s waitFor...() functions; these suspend the calling thread until a signal has been emitted. For example, after calling the non-blocking <a href="qabstractsocket.html#connectToHost">QTcpSocket::connectToHost</a>() function, call <a href="qabstractsocket.html#waitForConnected">QTcpSocket::waitForConnected</a>() to block the thread until the <a href="qabstractsocket.html#connected">connected()</a> signal has been emitted.</p>
<p>Synchronous sockets often lead to code with a simpler flow of control. The main disadvantage of the waitFor...() approach is that events won't be processed while a waitFor...() function is blocking. If used in the GUI thread, this might freeze the application's user interface. For this reason, we recommend that you use synchronous sockets only in non-GUI threads. When used synchronously, <a href="qtcpsocket.html">QTcpSocket</a> doesn't require an event loop.</p>
<p>The <a href="network-fortuneclient.html">Fortune Client</a> and <a href="network-fortuneserver.html">Fortune Server</a> examples show how to use <a href="qtcpsocket.html">QTcpSocket</a> and <a href="qtcpserver.html">QTcpServer</a> to write TCP client-server applications. See also <a href="network-blockingfortuneclient.html">Blocking Fortune Client</a> for an example on how to use a synchronous <a href="qtcpsocket.html">QTcpSocket</a> in a separate thread (without using an event loop), and <a href="network-threadedfortuneserver.html">Threaded Fortune Server</a> for an example of a multithreaded TCP server with one thread per active client.</p>
<a name="using-udp-with-qudpsocket"></a>
<h3>Using UDP with QUdpSocket</h3>
<p>UDP (User Datagram Protocol) is a lightweight, unreliable, datagram-oriented, connectionless protocol. It can be used when reliability isn't important. For example, a server that reports the time of day could choose UDP. If a datagram with the time of day is lost, the client can simply make another request.</p>
<p align="center"><img src="images/udppackets.png" alt="UDP Packets" /></p><p>The <a href="qudpsocket.html">QUdpSocket</a> class allows you to send and receive UDP datagrams. It inherits <a href="qabstractsocket.html">QAbstractSocket</a>, and it therefore shares most of <a href="qtcpsocket.html">QTcpSocket</a>'s interface. The main difference is that <a href="qudpsocket.html">QUdpSocket</a> transfers data as datagrams instead of as a continuous stream of data. In short, a datagram is a data packet of limited size (normally smaller than 512 bytes), containing the IP address and port of the datagram's sender and receiver in addition to the data being transferred.</p>
<p><a href="qudpsocket.html">QUdpSocket</a> supports IPv4 broadcasting. Broadcasting is often used to implement network discovery protocols, such as finding which host on the network has the most free hard disk space. One host broadcasts a datagram to the network that all other hosts receive. Each host that receives a request then sends a reply back to the sender with its current amount of free disk space. The originator waits until it has received replies from all hosts, and can then choose the server with most free space to store data. To broadcast a datagram, simply send it to the special address <a href="qhostaddress.html#SpecialAddress-enum">QHostAddress::Broadcast</a> (255.255.255.255), or to your local network's broadcast address.</p>
<p><a href="qudpsocket.html#bind">QUdpSocket::bind</a>() prepares the socket for accepting incoming datagrams, much like <a href="qtcpserver.html#listen">QTcpServer::listen</a>() for TCP servers. Whenever one or more datagrams arrive, <a href="qudpsocket.html">QUdpSocket</a> emits the <a href="qiodevice.html#readyRead">readyRead()</a> signal. Call <a href="qudpsocket.html#readDatagram">QUdpSocket::readDatagram</a>() to read the datagram.</p>
<p>The <a href="network-broadcastsender.html">Broadcast Sender</a> and <a href="network-broadcastreceiver.html">Broadcast Receiver</a> examples show how to write a UDP sender and a UDP receiver using Qt.</p>
<a name="resolving-host-names-using-qhostinfo"></a>
<h3>Resolving Host Names using QHostInfo</h3>
<p>Before establishing a network connection, <a href="qtcpsocket.html">QTcpSocket</a> and <a href="qudpsocket.html">QUdpSocket</a> perform a name lookup, translating the host name you're connecting to into an IP address. This operation is usually performed using the DNS (Domain Name Service) protocol.</p>
<p><a href="qhostinfo.html">QHostInfo</a> provides a static function that lets you perform such a lookup yourself. By calling <a href="qhostinfo.html#lookupHost">QHostInfo::lookupHost</a>() with a host name, a <a href="qobject.html">QObject</a> pointer, and a slot signature, <a href="qhostinfo.html">QHostInfo</a> will perform the name lookup and invoke the given slot when the results are ready. The actual lookup is done in a separate thread, making use of the operating system's own methods for performing name lookups.</p>
<p><a href="qhostinfo.html">QHostInfo</a> also provides a static function called <a href="qhostinfo.html#fromName">QHostInfo::fromName</a>() that takes the host name as argument and returns the results. In this case, the name lookup is performed in the same thread as the caller. This overload is useful for non-GUI applications or for doing name lookups in a separate, non-GUI thread. (Calling this function in a GUI thread may cause your user interface to freeze while the function blocks as it performs the lookup.)</p>
<p>
[Previous: <a href="qtgui.html">QtGui Module</a>]
[<a href="modules.html">Qt's Modules</a>]
[Next: <a href="qtopengl.html">QtOpenGL Module</a>]
</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright &copy; 2008 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt 4.3.5</div></td>
</tr></table></div></address></body>
</html>
